Release 10.1A: OpenEdge Development:
Web Services

Interacting with a Web service and its operations

The general procedure for accessing a Web service to invoke its operations is similar to accessing a session-free AppServer and invoking its remote procedures and user-defined functions, with some variation. For information on accessing a session-free AppServer, see OpenEdge Application Server: Developing AppServer Applications .

AppServer and Web service access compared

Table 1–2 lists and compares the 4GL elements used for session-free AppServer access and Web service access, listed in rough order of use.

Table 1–2: AppServer and Web service access compared

Session-free AppServer clients use the...	Web service clients use the...
Server object handle to access the AppServer application service.	Server object handle to access the Web service.
CONNECT( ) method on the server handle to logically connect (bind) the server object to the application service.	CONNECT( ) method on the server handle to logically connect (bind) the server object to the Web service.
RUN statement to instantiate a remote persistent procedure on an AppServer and map it to a proxy persistent procedure handle.	RUN statement to access a port type in the Web service and map it to a Web service proxy procedure handle.
RUN statement and the proxy persistent procedure handle to execute an internal procedure of the remote persistent procedure.	RUN statement and the Web service proxy procedure handle (Web service procedure object) to invoke an operation of the port type as a remote internal procedure. Note: All Web service operations can be invoked as remote internal procedures, allowing them to be invoked asynchronously. However, some Web service operations can also be invoked as remote user-defined functions.
FUNCTION prototype statement with the proxy procedure handle and function invocation to return the value of a remote user-defined function.	FUNCTION prototype statement with the Web service proxy procedure handle, and function invocation to return the value of a Web service operation that the WSDL Analyzer indicates can be invoked as a function.
NO-ERROR option and the ERROR-STATUS system handle to trap 4GL statement errors.	NO-ERROR option and the ERROR-STATUS system handle to trap 4GL statement errors and Web service SOAP faults.
Asynchronous request object handle to manage asynchronous execution of remote 4GL procedures.	Asynchronous request object handle to manage asynchronous invocation of Web service operations.
DISCONNECT( ) method on the server handle to logically disconnect (unbind) the server object from the application service.	DISCONNECT( ) method on the server handle to logically disconnect (unbind) the server object from the Web service.
DELETE object statement to delete object handles that are no longer needed.	DELETE object statement to delete object handles that are no longer needed.

Basic Web service access cycle

As you can see from Table 1–2, you can access a Web service using the same basic 4GL element framework used to access a session-free AppServer. The following sample code shows a working 4GL program that accesses the TemperatureService Web service. This is an actual public Web service whose WSDL file is available at the following location on the Internet:

http://www.xmethods.net/sd/2001/TemperatureService.wsdl

Note: While this is the URL to an actual Web service at this time of writing, the URL or availability of any public Web service can change at any time.

Sample Web service access

This is a simple Web service that allows you to get the current temperature for a United States zip code (hard-coded in the example). Here is the 4GL program that accesses it, with numbered comments (such as, /*2*/ or /*7*/) corresponding to the ordered description that follows:

DEFINE VARIABLE hWeatherWS AS HANDLE.   /*1*/ DEFINE VARIABLE hPortType AS HANDLE. DEFINE VARIABLE cTemp as CHARACTER. CREATE SERVER hWeatherWS. /*2*/ hWeatherWS:CONNECT /*3*/    ("-WSDL 'http://www.xmethods.net/sd/2001/TemperatureService.wsdl'"). RUN TemperaturePortType SET hPortType ON SERVER hWeatherWS NO-ERROR. /*4*/ RUN getTemp IN hPortType (INPUT "01730", OUTPUT cTemp). /*5*/ MESSAGE "The temperature is: " cTemp VIEW-AS ALERT-BOX. DELETE PROCEDURE hPortType. /*6*/ hWeatherWS:DISCONNECT(). /*7*/ DELETE OBJECT hWeatherWS. /*8*/

This code:

Creates two handles and a variable to receive Web service output:
hWeatherWS — To be used as the server object handle for the Web service.
hPortType — To be used as the Web service proxy procedure handle to map the port type that contains the requested Web service operation.
cTemp — To receive the current temperature value for the given zip code.
Creates the server object on hWeatherWS to use for binding the Web service.
Logically binds the Web service to the server object using the CONNECT( ) method, which specifies:
The location of the Web service WSDL file for run-time access.
The physical service and port (endpoint) through which all communications pass between the 4GL client and the Web service.

In this example, no service and port are is explicitly specified because there is only one valid service and port in the WSDL file. For information on the full range of binding options for Web services, see the Chapter 9, " Connecting to Web Services from the Progress 4GL."

Using the RUN statement syntax, creates the Web service proxy procedure object and maps it to the port type (TemperaturePortType) that defines the getTemp operation for the Web service.
Invokes the getTemp operation as a procedure for the ZIP code location input as "01730" and the temperature at that location output as cTemp and displayed in a message. For more information on mapping Web service port types and invoking operations on them, see the Chapter 10, " Invoking Web Service Operations from the Progress 4GL."
Deletes (cleans up) the hPortType procedure object, using the DELETE PROCEDURE statement, after it is no longer needed.
Unbinds the Web service from the hWeatherWS server object using the DISCONNECT( ) method on the hWeatherWS server handle.
Deletes (cleans up) the hWeatherWS server object, using the DELETE OBJECT statement, after it is no longer needed.
Note: At this point, the program can use the same hWeatherWS server object to bind to another Web service or another binding for the same Web service, perhaps to return humidity or wind speed at a zip code location using a different port type. If it is completely finished accessing Web services and AppServers, but has more work to do, it might clean up by deleting the hWeatherWS server object using the DELETE object statement.

For more information on managing Web service bindings, see the Chapter 9, " Connecting to Web Services from the Progress 4GL."

This sample shows the similarity between basic AppServer and Web service access using synchronous interaction with the client. Another common feature between client interaction with an AppServer and client interaction with a Web service is the ability to invoke procedures asynchronously. For information on when and what you need to do to invoke Web service requests asynchronously, see the "Managing asynchronous requests" section.

Note: This sample is not available on the Documentation and Samples CD or Progress Documentation Web site.

WSDL Analyzer as the client interface source

All of the information for writing the code in the previous example is likely to be found in the WSDL file used to bind the Web service at run time (often accessed directly from the WSDL URL location). If you run the WSDL Analyzer on the WSDL file to generate the interface documentation, it generates a hyperlinked document contain information on how to connect to and invoke operations in the Web service, such as the:

Connection parameters for the CONNECT( ) method.
Name of a Web service port type.
Prototypes for 4GL procedures and user-defined functions used to invoke Web service operations for a given port type.
Any complex types defined for use in Web service operation parameters.
Other information required to use the Web service, such as the way Web service errors (SOAP faults) are returned to the client.

For more information on running the WSDL Analyzer and the documentation that it generates, see Chapter 8, " Analyzing WSDL for Progress 4GL Access to Web Services."